MPATROL
Section: mpatrol library (3)
Updated: 16 May 2000
Index
Return to Main Contents
NAME
mpatrol - dynamic memory allocation and tracing library
SYNOPSIS
#include <mpatrol.h>
void *malloc(size_t size);
void *calloc(size_t nelem, size_t size);
void *memalign(size_t align, size_t size);
void *valloc(size_t size);
void *pvalloc(size_t size);
char *strdup(const char *str);
char *strndup(const char *str, size_t size);
char *strsave(const char *str);
char *strnsave(const char *str, size_t size);
void *realloc(void *ptr, size_t size);
void *recalloc(void *ptr, size_t nelem, size_t size);
void *expand(void *ptr, size_t size);
void free(void *ptr);
void cfree(void *ptr, size_t nelem, size_t size);
void *operator new(size_t size);
void *operator new[](size_t size);
void operator delete(void *ptr);
void operator delete[](void *ptr);
void (*set_new_handler(void (*func)(void)))(void);
void *memset(void *ptr, int byte, size_t size);
void bzero(void *ptr, size_t size);
void *memccpy(void *dest, const void *src, int byte,
size_t size);
void *memcpy(void *dest, const void *src, size_t size);
void *memmove(void *dest, const void *src, size_t size);
void bcopy(const void *src, void *dest, size_t size);
int memcmp(const void *ptr1, const void *ptr2,
size_t size);
int bcmp(const void *ptr1, const void *ptr2, size_t size);
void *memchr(const void *ptr, int byte, size_t size);
void *memmem(const void *ptr1, size_t size1,
const void *ptr2, size_t size2);
int __mp_info(const void *ptr, __mp_allocinfo *info);
int __mp_printinfo(const void *ptr);
void __mp_memorymap(int stats);
void __mp_summary(void);
void __mp_check(void);
void (*__mp_prologue(void (*func)(const void *, size_t)))
(const void *, size_t);
void (*__mp_epilogue(void (*func)(const void *)))
(const void *);
void (*__mp_nomemory(void (*func)(void)))(void);
DESCRIPTION
The mpatrol library contains implementations of dynamic memory
allocation functions for C and C++ suitable for tracing and debugging, and is
available on UNIX, AmigaOS, Windows and Netware platforms. The library is
intended to be used without requiring any changes to existing user source code
except the inclusion of the mpatrol.h header file, although additional
functions are supplied for extra tracing and control. Note that the current
version of the mpatrol library is contained in the MPATROL_VERSION
preprocessor macro.
All of the function definitions in mpatrol.h can be disabled by defining
the NDEBUG preprocessor macro, which is the same macro used to control
the behaviour of the assert function. If NDEBUG is defined then
no macro redefinition of functions will take place and all special mpatrol
library functions will evaluate to empty statements. It is intended that the
NDEBUG preprocessor macro be defined in release builds.
All diagnostics are sent to the file mpatrol.log in the current directory
by default but this can be changed at run-time. Additional configuration
options can also be changed at run-time by setting and altering the
MPATROL_OPTIONS environment variable. See ENVIRONMENT below for
more details.
Details of memory allocations and free memory are stored internally as a tree
structure for speed and also to allow the best fit allocation algorithm to be
used. This also enables the library to perform intelligent resizing of memory
allocations and can be used to quickly determine if an address has been
allocated on the heap.
On systems that support memory protection, the library attempts to detect any
illegal memory accesses and display as much information as it can obtain about
the address in question and where the illegal memory access occurred.
Stack traceback information for every memory allocation is available on some
supported platforms, which is useful for determining exactly where a memory
allocation was performed or for adding meaning to tracing. Symbol names are
read from the executable file and also possibly from any required shared
libraries, and if the USEDEBUG option is used and is available then the
debugging section in the executable file will be read to determine additional
source-level information.
Memory allocation profiling is supported, with statistics about every memory
allocation and deallocation that was made during the execution of a program
being written to a file at program termination if the PROF option is
used. The information stored in this file can then be used by the mprof
command to display various tables summarising the memory allocation behaviour
of the program that produced it.
FUNCTIONS
The following 14 functions are available as replacements for existing C library
functions. To use these you must include mpatrol.h before all other
header files, although on UNIX and Windows platforms (and AmigaOS when using
gcc) they will be used anyway, albeit with slightly less tracing
information:
- malloc
-
Allocates size uninitialised bytes from the heap and returns a pointer to
the first byte of the allocation. The pointer returned will be suitably
aligned for casting to any type and can be used to store data of up to
size bytes in length. If size is 0 then the memory allocated
will be implicitly rounded up to 1 byte. If there is not enough space in
the heap then the null pointer will be returned and errno will be set to
ENOMEM. The allocated memory must be deallocated with free or
reallocated with realloc.
- calloc
-
Allocates nelem elements of size zero-initialised bytes from the
heap and returns a pointer to the first byte of the allocation. The pointer
returned will be suitably aligned for casting to any type and can be used to
store data of up to nelem * size bytes in length. If nelem * size
is 0 then the amount of memory allocated will be implicitly rounded up to
1 byte. If there is not enough space in the heap then the null pointer
will be returned and errno will be set to ENOMEM. The allocated
memory must be deallocated with free or reallocated with realloc.
- memalign
-
Allocates size uninitialised bytes from the heap and returns a pointer to
the first byte of the allocation. The pointer returned will be aligned to
align bytes and can be used to store data of up to size bytes in
length. If align is zero then the default system alignment will be used.
If align is not a power of two then it will be rounded up to the nearest
power of two. If align is greater than the system page size then it will
be truncated to that value. If size is 0 then the memory allocated
will be implicitly rounded up to 1 byte. If there is not enough space in
the heap then the null pointer will be returned and errno will be set to
ENOMEM. The allocated memory must be deallocated with free or
reallocated with realloc, although the latter will not guarantee the
preservation of alignment.
- valloc
-
Allocates size uninitialised bytes from the heap and returns a pointer to
the first byte of the allocation. The pointer returned will be aligned to the
system page size and can be used to store data of up to size bytes in
length. If size is 0 then the memory allocated will be implicitly
rounded up to 1 byte. If there is not enough space in the heap then the
null pointer will be returned and errno will be set to ENOMEM. The
allocated memory must be deallocated with free or reallocated with
realloc, although the latter will not guarantee the preservation of
alignment.
- pvalloc
-
Allocates size uninitialised bytes from the heap and returns a pointer to
the first byte of the allocation. The pointer returned will be aligned to the
system page size and can be used to store data of up to size bytes in
length. If size is 0 then the memory allocated will be implicitly
rounded up to 1 page, otherwise size will be implicitly rounded up
to a multiple of the system page size. If there is not enough space in the heap
then the null pointer will be returned and errno will be set to
ENOMEM. The allocated memory must be deallocated with free or
reallocated with realloc, although the latter will not guarantee the
preservation of alignment.
- strdup
-
Allocates exactly enough memory from the heap to duplicate str (including
the terminating nul character) and returns a pointer to the first byte of the
allocation after copying str to the newly-allocated memory. The pointer
returned will have no alignment constraints and can be used to store character
data up to the length of str. If str is NULL then the null
pointer will be returned. If there is not enough space in the heap then the
null pointer will be returned and errno will be set to ENOMEM. The
allocated memory must be deallocated with free or reallocated with
realloc.
- strndup
-
Allocates exactly enough memory from the heap to duplicate str (including
the terminating nul character) and returns a pointer to the first byte of the
allocation after copying str to the newly-allocated memory. The pointer
returned will have no alignment constraints and can be used to store character
data up to the length of str. If str is NULL then the null
pointer will be returned. If the length of str is greater than size
then only size characters will be allocated and copied, with one
additional byte for the nul character. If there is not enough space in the heap
then the null pointer will be returned and errno will be set to
ENOMEM. The allocated memory must be deallocated with free or
reallocated with realloc. This function is available for backwards
compatibility with older C libraries and should not be used in new code.
- strsave
-
Allocates exactly enough memory from the heap to duplicate str (including
the terminating nul character) and returns a pointer to the first byte of the
allocation after copying str to the newly-allocated memory. The pointer
returned will have no alignment constraints and can be used to store character
data up to the length of str. If str is NULL then the null
pointer will be returned. If there is not enough space in the heap then the
null pointer will be returned and errno will be set to ENOMEM. The
allocated memory must be deallocated with free or reallocated with
realloc. This function is available for backwards compatibility with
older C libraries and should not be used in new code.
- strnsave
-
Allocates exactly enough memory from the heap to duplicate str (including
the terminating nul character) and returns a pointer to the first byte of the
allocation after copying str to the newly-allocated memory. The pointer
returned will have no alignment constraints and can be used to store character
data up to the length of str. If str is NULL then the null
pointer will be returned. If the length of str is greater than size
then only size characters will be allocated and copied, with one
additional byte for the nul character. If there is not enough space in the heap
then the null pointer will be returned and errno will be set to
ENOMEM. The allocated memory must be deallocated with free or
reallocated with realloc. This function is available for backwards
compatibility with older C libraries and should not be used in new code.
- realloc
-
Resizes the memory allocation beginning at ptr to size bytes and
returns a pointer to the first byte of the new allocation after copying
ptr to the newly-allocated memory, which will be truncated if size
is smaller than the original allocation. The pointer returned will be suitably
aligned for casting to any type and can be used to store data of up to
size bytes in length. If ptr is NULL then the call will be
equivalent to malloc. If size is 0 then the existing memory
allocation will be freed and the null pointer will be returned. If size
is greater than the original allocation then the extra space will be filled with
uninitialised bytes. If there is not enough space in the heap then the null
pointer will be returned and errno will be set to ENOMEM. The
allocated memory must be deallocated with free and can be reallocated
again with realloc.
- recalloc
-
Resizes the memory allocation beginning at ptr to nelem elements of
size bytes and returns a pointer to the first byte of the new allocation
after copying ptr to the newly-allocated memory, which will be truncated
if nelem * size is smaller than the original allocation. The
pointer returned will be suitably aligned for casting to any type and can be
used to store data of up to nelem * size bytes in length. If
ptr is NULL then the call will be equivalent to calloc. If
nelem * size is 0 then the existing memory allocation will be
freed and the null pointer will be returned. If nelem * size is
greater than the original allocation then the extra space will be filled with
zero-initialised bytes. If there is not enough space in the heap then the null
pointer will be returned and errno will be set to ENOMEM. The
allocated memory must be deallocated with free and can be reallocated
again with realloc. This function is available for backwards
compatibility with older C libraries and calloc and should not be used in
new code.
- expand
-
Attempts to resize the memory allocation beginning at ptr to size
bytes and either returns ptr if there was enough space to resize it, or
NULL if the block could not be resized for a particular reason. If
ptr is NULL then the call will be equivalent to malloc. If
size is 0 then the existing memory allocation will be freed and the
NULL pointer will be returned. If size is greater than the original
allocation then the extra space will be filled with uninitialised bytes and if
size is less than the original allocation then the memory block will be
truncated. If there is not enough space in the heap then the NULL pointer
will be returned and errno will be set to ENOMEM. The allocated
memory must be deallocated with free and can be reallocated again with
realloc. This function is available for backwards compatibility with
older C libraries and should not be used in new code.
- free
-
Frees the memory allocation beginning at ptr so the memory can be reused
by another call to allocate memory. If ptr is NULL then no memory
will be freed. All of the previous contents will be destroyed.
- cfree
-
Frees the memory allocation beginning at ptr so the memory can be reused
by another call to allocate memory. If ptr is NULL then no memory
will be freed. All of the previous contents will be destroyed. The nelem
and size parameters are ignored in this implementation. This function is
available for backwards compatibility with older C libraries and calloc
and should not be used in new code.
The following 5 functions are available as replacements for existing C++ library
functions, but the replacements in mpatrol.h will only be used if the
MP_NOCPLUSPLUS preprocessor macro is not defined. To use these you must
include mpatrol.h before all other header files, although on UNIX and
Windows platforms (and AmigaOS when using gcc) they will be used anyway,
albeit with slightly less tracing information:
- operator new
-
Allocates size uninitialised bytes from the heap and returns a pointer to
the first byte of the allocation. The pointer returned will be suitably
aligned for casting to any type and can be used to store data of up to
size bytes in length. If size is 0 then the memory allocated
will be implicitly rounded up to 1 byte. If there is not enough space in
the heap then the null pointer will be returned and errno will be set to
ENOMEM - no exceptions will be thrown. The allocated memory must be
deallocated with operator delete.
- operator new[]
-
Allocates size uninitialised bytes from the heap and returns a pointer to
the first byte of the allocation. The pointer returned will be suitably
aligned for casting to any type and can be used to store data of up to
size bytes in length. If size is 0 then the memory allocated
will be implicitly rounded up to 1 byte. If there is not enough space in
the heap then the null pointer will be returned and errno will be set to
ENOMEM - no exceptions will be thrown. The allocated memory must be
deallocated with operator delete[].
- operator delete
-
Frees the memory allocation beginning at ptr so the memory can be reused
by another call to allocate memory. If ptr is NULL then no memory
will be freed. All of the previous contents will be destroyed. This function
must only be used with memory allocated by operator new.
- operator delete[]
-
Frees the memory allocation beginning at ptr so the memory can be reused
by another call to allocate memory. If ptr is NULL then no memory
will be freed. All of the previous contents will be destroyed. This function
must only be used with memory allocated by operator new[].
- set_new_handler
-
Installs a low-memory handler specifically for use with operator new and
operator new[] and returns a pointer to the previously installed handler,
or the null pointer if no handler had been previously installed. This will be
called repeatedly by both functions when they would normally return NULL,
and this loop will continue until they manage to allocate the requested space.
The default low-memory handler for the C++ operators will terminate the program
and write an out of memory message to the log file. Note that this function is
equivalent to __mp_nomemory and will replace the handler installed by that
function.
The following 10 functions are available as replacements for existing C library
memory operation functions. To use these you must include mpatrol.h
before all other header files, although on UNIX and Windows platforms (and
AmigaOS when using gcc) they will be used anyway, albeit with slightly
less tracing information:
- memset
-
Writes size bytes of value byte to the memory location beginning at
ptr and returns ptr. If size is 0 then no bytes will
be written. If the operation would affect an existing memory allocation in the
heap but would straddle that allocation's boundaries then an error message will
be generated in the log file and no bytes will be written.
- bzero
-
Writes size zero bytes to the memory location beginning at ptr. If
size is 0 then no bytes will be written. If the operation would
affect an existing memory allocation in the heap but would straddle that
allocation's boundaries then an error message will be generated in the log file
and no bytes will be written. This function is available for backwards
compatibility with older C libraries and should not be used in new code.
- memccpy
-
Copies size bytes from src to dest and returns NULL, or
copies the number of bytes up to and including the first occurrence of
byte if byte exists within the specified range and returns a pointer
to the first byte after byte. If size is 0 or src is
the same as dest then no bytes will be copied. The source and destination
ranges should not overlap, otherwise a warning will be written to the log file.
If the operation would affect an existing memory allocation in the heap but
would straddle that allocation's boundaries then an error message will be
generated in the log file and no bytes will be copied.
- memcpy
-
Copies size bytes from src to dest and returns dest. If
size is 0 or src is the same as dest then no bytes will
be copied. The source and destination ranges should not overlap, otherwise a
warning will be written to the log file. If the operation would affect an
existing memory allocation in the heap but would straddle that allocation's
boundaries then an error message will be generated in the log file and no bytes
will be copied.
- memmove
-
Copies size bytes from src to dest and returns dest. If
size is 0 or src is the same as dest then no bytes will
be copied. If the operation would affect an existing memory allocation in the
heap but would straddle that allocation's boundaries then an error message will
be generated in the log file and no bytes will be copied.
- bcopy
-
Copies size bytes from src to dest. If size is 0
or src is the same as dest then no bytes will be copied. If the
operation would affect an existing memory allocation in the heap but would
straddle that allocation's boundaries then an error message will be generated in
the log file and no bytes will be copied. This function is available for
backwards compatibility with older C libraries and should not be used in new
code.
- memcmp
-
Compares size bytes from ptr1 and ptr2 and returns 0 if
all of the bytes are identical, or returns the byte difference of the first
differing bytes. If size is 0 or ptr1 is the same as
ptr2 then no bytes will be compared. If the operation would read from an
existing memory allocation in the heap but would straddle that allocation's
boundaries then an error message will be generated in the log file and no bytes
will be compared.
- bcmp
-
Compares size bytes from ptr1 and ptr2 and returns 0 if
all of the bytes are identical, or returns the byte difference of the first
differing bytes. If size is 0 or ptr1 is the same as
ptr2 then no bytes will be compared. If the operation would read from an
existing memory allocation in the heap but would straddle that allocation's
boundaries then an error message will be generated in the log file and no bytes
will be compared. This function is available for backwards compatibility with
older C libraries and should not be used in new code.
- memchr
-
Searches up to size bytes in ptr for the first occurrence of
byte and returns a pointer to it or NULL if no such byte occurs. If
size is 0 then no bytes will be searched. If the operation would
affect an existing memory allocation in the heap but would straddle that
allocation's boundaries then an error message will be generated in the log file
and no bytes will be searched.
- memmem
-
Searches up to size1 bytes in ptr1 for the first occurrence of
ptr2 (which is exactly size2 bytes in length) and returns a pointer
to it or NULL if no such sequence of bytes occur. If size1 or
size2 is 0 then no bytes will be searched. If the operation would
affect an existing memory allocation in the heap but would straddle that
allocation's boundaries then an error message will be generated in the log file
and no bytes will be searched.
The following 8 functions are available as support routines for additional
control and tracing in the mpatrol library. To use these you should include the
mpatrol.h header file:
- __mp_info
-
Obtains information about a specific memory allocation by placing statistics
about ptr in info. If ptr does not belong to a previously
allocated memory allocation then 0 will be returned, otherwise 1
will be returned and info will contain the following information:
-
Field Description
block Pointer to first byte of alloc.
size Size of alloc in bytes.
type Type of function which allocated memory.
alloc Allocation index.
realloc Number of times reallocated.
thread Thread identifier.
func Function in which alloc took place.
file File in which alloc took place.
line Line number at which alloc took place.
stack Pointer to function call stack.
freed Indicates if alloc has been freed.
- __mp_printinfo
-
Displays information about a specific memory allocation containing ptr to
the standard error file stream. If ptr does not belong to a previously
allocated memory allocation then 0 will be returned, otherwise 1
will be returned. This function is intended to be called from within a
debugger.
- __mp_memorymap
-
If stats is non-zero then the current statistics of the mpatrol library
will be displayed. If the heap contains at least one allocated, freed or free
block then a map of the current heap will also be displayed.
- __mp_summary
-
Displays information about the current state of the mpatrol library, including
its settings and any relevant statistics.
- __mp_check
-
Forces the library to perform an immediate check of the overflow buffers of
every memory allocation and to ensure that nothing has overwritten any free
blocks.
- __mp_prologue
-
Installs a prologue function to be called before any memory allocation,
reallocation or deallocation function. This function will return a pointer to
the previously installed prologue function, or the null pointer if no prologue
function had been previously installed. The following arguments will be used
to call the prologue function:
-
Argument 1 Argument 2 Called by
-1 size malloc, etc.
ptr size realloc, etc.
ptr -1 free, etc.
ptr -2 strdup, etc.
- __mp_epilogue
-
Installs an epilogue function to be called after any memory allocation,
reallocation or deallocation function. This function will return a pointer to
the previously installed epilogue function, or the null pointer if no epilogue
function had been previously installed. The following arguments will be used
to call the epilogue function:
-
Argument Called by
ptr malloc, realloc, strdup, etc.
-1 free, etc.
- __mp_nomemory
-
Installs a low-memory handler and returns a pointer to the previously installed
handler, or the null pointer if no handler had been previously installed. This
will be called once by C memory allocation functions, and repeatedly by C++
memory allocation functions, when they would normally return NULL. Note
that this function is equivalent to set_new_handler and will replace the
handler installed by that function.
LINKING
In order to use the mpatrol library on UNIX platforms, the following libraries
must be linked in before any other library that defines dynamic memory
allocation functions with the same names:
-
Library Reason
-lmpatrol To use this library.
-lelf If built with FORMAT=FORMAT_ELF32.
-lbfd -liberty If built with FORMAT=FORMAT_BFD.
-lpthread If built with MP_THREADS_SUPPORT.
On UNIX platforms, if there were no calls to memory allocation functions before
-lmpatrol appears on the link line then the mpatrol library will not be
linked in. However, this can be overridden by placing -umalloc just
before that point.
You may also wish to set your core file size limit to be zero before running
any programs linked with the mpatrol library as the extra memory that the
library uses can make such files much larger than normal, and if you are
planning on using a symbolic debugger then you won't need the core files anyway.
ENVIRONMENT
The library can read certain options at run-time from an environment variable
called MPATROL_OPTIONS. This variable must contain one or more valid
option keywords from the list below and must be no longer than 1024 characters
in length. If MPATROL_OPTIONS is unset or empty then the default settings
will be used.
The syntax for options specified within the MPATROL_OPTIONS environment
variable is OPTION or OPTION=VALUE, where OPTION is a
keyword from the list below and VALUE is the setting for that option. If
VALUE is numeric then it may be specified using binary, octal, decimal or
hexadecimal notation, with binary notation beginning with either 0b or
0B. If VALUE is a character string containing spaces then it may be
quoted using double quotes. No whitespace may appear between the = sign,
but whitespace must appear between different options. Note that option keywords
can be given in lowercase as well as uppercase, or a mixture of both.
- ALLOCBYTE=unsigned integer
-
Specifies an 8-bit byte pattern with which to prefill newly-allocated memory.
This can be used to detect the use of memory which has not been initialised
after allocation. Note that this setting will not affect memory allocated with
calloc or recalloc as these functions always prefill allocated
memory with an 8-bit byte pattern of zero. Default value:
ALLOCBYTE=0xFF.
- ALLOCSTOP=unsigned integer
-
Specifies an allocation index at which to stop the program when it is being
allocated. When the number of memory allocations reaches this number the
program will be halted, and its state may be examined at that point by using
a suitable debugger. Note that this setting will be ignored if its value is
zero. Default value: ALLOCSTOP=0.
- ALLOWOFLOW
-
Specifies that a warning rather than an error should be produced if any memory
operation function overflows the boundaries of a memory allocation, and that
the operation should still be performed. This option is provided for
circumstances where it is desirable for the memory operation to be performed,
regardless of whether it is erroneous or not.
- AUTOSAVE=unsigned integer
-
Specifies the frequency at which to periodically write the profiling data to
the profiling output file. When the total number of profiled memory allocations
and deallocations is a multiple of this number then the current profiling
information will be written to the profiling output file. This option can be
used to instruct the mpatrol library to dump out any profiling information just
before a fatal error occurs in a program, for example. Note that this setting
will be ignored if its value is zero. Default value: AUTOSAVE=0.
- CHECK=unsigned range
-
Specifies a range of allocation indices at which to check the integrity of free
memory and overflow buffers. The range must be specified as no more than two
unsigned integers separated by a dash. If numbers on either the left side or
the right side of the dash are omitted then they will be assumed to be 0
and infinity respectively. A value of 0 on its own indicates that
no such checking will ever be performed. This option can be used to speed up
the execution speed of the library at the expense of checking. Default value:
CHECK=-.
- CHECKALL
-
Equivalent to the CHECKALLOCS, CHECKREALLOCS and CHECKFREES
options specified together.
- CHECKALLOCS
-
Checks that no attempt is made to allocate a block of memory of size zero. A
warning will be issued for every such case.
- CHECKFREES
-
Checks that no attempt is made to deallocate a NULL pointer. A warning
will be issued for every such case.
- CHECKREALLOCS
-
Checks that no attempt is made to reallocate a NULL pointer or resize an
existing block of memory to size zero. Warnings will be issued for every such
case.
- DEFALIGN=unsigned integer
-
Specifies the default alignment for general-purpose memory allocations, which
must be a power of two (and will be rounded up to the nearest power of two if it
is not). The default alignment for a particular system is calculated at
run-time.
- FAILFREQ=unsigned integer
-
Specifies the frequency at which all memory allocations will randomly fail. For
example, a value of 10 will mean that roughly 1 in 10 memory allocations
will fail, but a value of 0 will disable all random failures. This option
can be useful for stress-testing an application. Default value:
FAILFREQ=0.
- FAILSEED=unsigned integer
-
Specifies the random number seed which will be used when determining which
memory allocations will randomly fail. A value of 0 will instruct the
library to pick a random seed every time it is run. Any other value will mean
that the random failures will be the same every time the program is run, but
only as long as the seed stays the same. Default value: FAILSEED=0.
- FREEBYTE=unsigned integer
-
Specifies an 8-bit byte pattern with which to prefill newly-freed memory. This
can be used to detect the use of memory which has just been freed. It is also
used internally to ensure that freed memory has not been overwritten. Note that
the freed memory may be reused the next time a block of memory is allocated and
so once memory has been freed its contents are not guaranteed to remain the same
as the specified byte pattern. Default value: FREEBYTE=0x55.
- FREESTOP=unsigned integer
-
Specifies an allocation index at which to stop the program when it is being
freed. When the memory allocation with the specified allocation index is to be
freed the program will be halted, and its state may be examined at that point
using a suitable debugger. Note that this setting will be ignored if its value
is zero. Default value: FREESTOP=0.
- HELP
-
Displays a quick-reference option summary to the stderr file stream.
- LARGEBOUND=unsigned integer
-
Specifies the limit in bytes up to which memory allocations should be classified
as large allocations for profiling purposes. This limit must be greater than
the small and medium bounds. Default value: LARGEBOUND=2048.
- LIMIT=unsigned integer
-
Specifies the limit in bytes at which all memory allocations should fail if the
total allocated memory should increase beyond this. This can be used to
stress-test software to see how it behaves in low memory conditions. The
internal memory used by the library itself will not be counted as part of the
total heap size, but on some systems there may be a small amount of memory
required to initialise the library itself. Note that this setting will be
ignored if its value is zero. Default value: LIMIT=0.
- LOGALL
-
Equivalent to the LOGALLOCS, LOGREALLOCS, LOGFREES and
LOGMEMORY options specified together.
- LOGALLOCS
-
Specifies that all memory allocations are to be logged and sent to the log file.
Note that any memory allocations made internally by the library will not be
logged.
- LOGFILE=string
-
Specifies an alternative file in which to place all diagnostics from the mpatrol
library. A filename of stderr will send all diagnostics to the
stderr file stream and a filename of stdout will do the equivalent
with the stdout file stream. Note that if a problem occurs while opening
the log file or if any diagnostics require to be displayed before the log file
has had a chance to be opened then they will be sent to the stderr file
stream. Default value: LOGFILE=mpatrol.log
- LOGFREES
-
Specifies that all memory deallocations are to be logged and sent to the log
file. Note that any memory deallocations made internally by the library will
not be logged.
- LOGMEMORY
-
Specifies that all memory operations are to be logged and sent to the log file.
These operations will be made by calls to functions such as memset and
memcpy. Note that any memory operations made internally by the library
will not be logged.
- LOGREALLOCS
-
Specifies that all memory reallocations are to be logged and sent to the log
file. Note that any memory reallocations made internally by the library will
not be logged.
- MEDIUMBOUND=unsigned integer
-
Specifies the limit in bytes up to which memory allocations should be classified
as medium allocations for profiling purposes. This limit must be greater than
the small bound but less than the large bound. Default value:
MEDIUMBOUND=256.
- NOFREE
-
Specifies that the mpatrol library should keep all reallocated and freed memory
allocations. Such freed memory allocations will then be flagged as freed and
can be used by the library to provide better diagnostics. However, as no system
memory will ever be reused by the mpatrol library, this option can quickly lead
to a shortage of available system memory for a process. Note that this option
will always force a memory reallocation to return a pointer to newly-allocated
memory, but the expand function will never be affected by this option.
- NOPROTECT
-
Specifies that the mpatrol library's internal data structures should not be made
read-only after every memory allocation reallocation or deallocation. This may
significantly speed up execution but this will be at the expense of less safety
if the program accidentally overwrites some of the library's internal data
structures. Note that this option has no effect on systems that do not support
memory protection.
- OFLOWBYTE=unsigned integer
-
Specifies an 8-bit byte pattern with which to fill the overflow buffers of all
memory allocations. This is used internally to ensure that nothing has been
written beyond the beginning or the end of a block of allocated memory. Note
that this setting will only have an effect if the OFLOWSIZE option is in
use. Default value: OFLOWBYTE=0xAA.
- OFLOWSIZE=unsigned integer
-
Specifies the size in bytes to use for all overflow buffers, which must be a
power of two (and will be rounded up to the nearest power of two if it is not).
This is used internally to ensure that nothing has been written beyond the
beginning or the end of a block of allocated memory. Note that this setting
specifies the size for only one of the overflow buffers given to each memory
allocation; the other overflow buffer will have an identical size. No overflow
buffers will be used if this setting is zero. Default value:
OFLOWSIZE=0.
- OFLOWWATCH
-
Specifies that watch point areas should be used for overflow buffers rather than
filling with the overflow byte. This can significantly reduce the speed of
program execution. Note that this option has no effect on systems that do not
support watch point areas.
- PAGEALLOC=LOWER|UPPER
-
Specifies that each individual memory allocation should occupy at least one
page of virtual memory and should be placed at the lowest or highest point
within these pages. This allows the library to place an overflow buffer of one
page on either side of every memory allocation and write-protect these pages as
well as all free and freed memory. Note that this option has no effect on
systems that do not support memory protection, and is disabled by default on
other systems as it can slow down the speed of program execution.
- PRESERVE
-
Specifies that any reallocated or freed memory allocations should preserve their
original contents. This option must be used with the NOFREE option and
has no effect otherwise.
- PROF
-
Specifies that all memory allocations and deallocations are to be profiled and
sent to the profiling output file. Memory reallocations are treated as a
memory deallocation immediately followed by a memory allocation.
- PROFFILE=string
-
Specifies an alternative file in which to place all memory allocation profiling
information from the mpatrol library. A filename of stderr will send this
information to the stderr file stream and a filename of stdout will
do the equivalent with the stdout file stream. Note that if a problem
occurs while opening the profiling output file then the profiling information
will be sent to the stderr file stream. Default value:
PROFFILE=mpatrol.out.
- PROGFILE=string
-
Specifies an alternative filename with which to locate the executable file
containing the program's symbols. On most systems, the library will
automatically be able to determine this filename, but on a few systems this
option may have to be used before any or all symbols can be read.
- REALLOCSTOP=unsigned integer
-
Specifies a reallocation index at which to stop the program when a memory
allocation is being reallocated. If the ALLOCSTOP option is non-zero
then the program will be halted when the allocation matching that allocation
index is reallocated the specified number of times. Otherwise the program will
be halted the first time any allocation is reallocated the specified number of
times. Note that this setting will be ignored if its value is zero. Default
value: REALLOCSTOP=0.
- SAFESIGNALS
-
Instructs the library to save and replace certain signal handlers during the
execution of library code and to restore them afterwards. This was the default
behaviour in version 1.0 of the mpatrol library and was changed since some
memory-intensive programs became very hard to interrupt using the keyboard,
thus giving the impression that the program or system had hung.
- SHOWALL
-
Equivalent to the SHOWFREED, SHOWUNFREED, SHOWMAP and
SHOWSYMBOLS options specified together.
- SHOWFREED
-
Specifies that a summary of all of the freed memory allocations should be
displayed at the end of program execution. This option must be used in
conjunction with the NOFREE option and this step will not be performed if
an abnormal termination occurs or if there were no freed allocations.
- SHOWMAP
-
Specifies that a memory map of the entire heap should be displayed at the end of
program execution. This step will not be performed if an abnormal termination
occurs or if the heap is empty.
- SHOWSYMBOLS
-
Specifies that a summary of all of the function symbols read from the program's
executable file should be displayed at the end of program execution. This step
will not be performed if an abnormal termination occurs or if no symbols could
be read from the executable file.
- SHOWUNFREED
-
Specifies that a summary of all of the unfreed memory allocations should be
displayed at the end of program execution. This step will not be performed if
an abnormal termination occurs or if there are no unfreed allocations.
- SMALLBOUND=unsigned integer
-
Specifies the limit in bytes up to which memory allocations should be classified
as small allocations for profiling purposes. This limit must be greater than
zero but less than the medium and large bounds. Default value:
SMALLBOUND=32.
- UNFREEDABORT=unsigned integer
-
Specifies the minimum number of unfreed allocations at which to abort the
program just before program termination. A summary of all the allocations will
be displayed on the standard error file stream before aborting. This option may
be handy for use in batch tests as it can force tests to fail if they do not
free up a minimum number of memory allocations. Note that this setting will be
ignored if its value is zero. Default value: UNFREEDABORT=0.
- USEDEBUG
-
Specifies that any debugging information in the executable file should be used
to obtain additional source-level information. This option will only have an
effect if the executable file contains a compiler-generated line number table
and will be ignored if the mpatrol library was built to support an object file
access library that cannot read line tables from object files.
- USEMMAP
-
Specifies that the library should use mmap instead of sbrk to
allocate system memory on UNIX platforms. This option should be used if there
are problems when using the mpatrol library in combination with another malloc
library which uses sbrk to allocate its memory. It is ignored on
systems that do not support the mmap system call.
SEE ALSO
mpatrol(1), mprof(1), mleak(1), mmap(2), sbrk(2),
malloc(3), memory(3), string(3), assert(3),
elf(3e), bfd(3).
The mpatrol manual, reference card and FAQ.
http://www.cbmamiga.demon.co.uk/mpatrol/
AUTHOR
Graeme S. Roy <graeme@epc.co.uk>
COPYRIGHT
Copyright (C) 1997-2000 Graeme S. Roy <graeme@epc.co.uk>
This library is free software; you can redistribute it and/or modify it under
the terms of the GNU Library General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option) any
later version.
This library is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more
details.
You should have received a copy of the GNU Library General Public License
along with this library; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- FUNCTIONS
-
- LINKING
-
- ENVIRONMENT
-
- SEE ALSO
-
- AUTHOR
-
- COPYRIGHT
-
This document was created by
man2html,
using the manual pages.
Time: 12:37:26 GMT, July 10, 2022